Apple Developer Connection 1998 Fall: Game Toolkit/Disc.iso/SDKs/PCI Driver Development Kit/• Tools/Utility/DisplayNameRegistry 950412/Src/AppleEventCore.h

Text File | 1997-02-27 | 12.7 KB | 422 lines | [TEXT/MPCC]

/*                                    AppleEventCore.h                            */
/*
 * AppleEventCore.h
 * Copyright © 1988-94 Apple Computer Inc. All rights reserved.
 *
 * Simple functions to integrate AppleEvents into "normal" applications. This
 * library handles the four required AppleEvents (init, open, print, quit)
 * and has a few routines to simplify access to event parameters.
 *
 * Usage:
 *
 *    pascal OSErr                InitializeAppleEvents(
 *            AEOpenAppHandlerFunc    aeOpenAppHandlerFunc,
 *            AEDocumentHandlerFunc    aeOpenDocHandlerFunc,
 *            AEDocumentHandlerFunc    aePrintDocHandlerFunc,
 *            AEQuitAppHandlerFunc    aeQuitAppHandlerFunc,
 *            AEDoScriptHandlerFunc    aeDoScriptHandlerFunc,
 *            AEUnknownHandlerMsgFunc    aeUnknownHandlerMsgFunc,
 *            long                    refCon
 *        );
 *
 *        Call this as part of your application startup process (after initializing
 *        the managers, but before calling WaitNextEvent). It returns noErr on
 *        success, or some system error (gestaltUndefSelectorErr if AppleEvents are
 *        not supported). DoHighLevelEvent will call one of the handler functions
 *        when the appropriate event occurs. The table pointers let your application
 *        install its own handler and coercion functions. The library installs
 *        "ignore" functions for the AppleScript recording events. The library does
 *        not install any coercion events. Pass NULL if you don't support one of
 *        the functions (but do support OpenApp and Quit).
 *
 *        The refCon will be passed back to the handler functions.
 *
 *        If aeDoScriptHandlerFunc is provided, script AppleEvents ('misc', 'dosc')
 *        will be passed to the handler with the key data ('----') stored in a
 *        character string (null-terminated C-string).
 *
 *        If aeUnknownHandlerMsgFunc is not NULL, it will be called with a text
 *        message if an unknown event is encounteres. The caller can display a
 *        non-fatal error alert (don't forget to call AEInteractionOK first).
 *
 *        After InitializeAppleEvents returns noErr, call AEInstallEventHandlers
 *        and/or AEInstallCoercionHandlers to install application-specific handlers.
 *
 *        The document handlers should only return an error status if the entire
 *        open/print handler should be terminated: errors that are unique to a
 *        single file should not be returned to the handler.
 *
 *    pascal OSErr                AEInstallEventHandlers(
 *            AEHandlerDefPtr            aeHandlerDefPtr,
 *            long                    refCon
 *        );
 *
 *        Install event handlers from a pre-compiled table. All handlers will have
 *        a common refCon.
 *
 *    pascal OSErr                AEInstallCoercionHandlers(
 *            AECoercionDefPtr        aeCoercionDefPtr,
 *            long                    refCon
 *        );
 *
 *        Install coercion handlers from a pre-compiled table. All handlers will
 *        have a common refCon.

 *
 *        To process events, add the following to your application event loop:
 *            status = AEProcessAppleEvent(eventRecordPtr);
 *        All the work is done by handler functions.
 *
 *    pascal OSErr                AEIgnore(
 *            const AppleEvent        *theEvent,
 *            AppleEvent                *theReply,
 *            long                    refCon
 *        );
 *
 *        This is for the convenience of application event handlers installation.
 *
 * The following are not directly used to handle AppleEvents.
 *
 *    pascal OSErr                AEHandlerSetup(
 *            const AppleEvent        *theEvent,
 *            AppleEvent                *theReply,
 *            long                    refCon
 *        );
 *
 *    All handlers should call this function at the start of processing. It stores
 *    the parameters in a global area for debugging convenience, and initializes
 *    some variables. Handlers should act as follows:
 *
 *            status = AEHandlerSetup(theEvent, theReply, refCon);
 *            if (status == noErr) {
 *                ... Get required parameters ...
 *                status = AEGotRequiredParams(theEvent);
 *                ... Get optional parameters ...
 *            }
 *            if (status == noErr) {
 *                ... Process the event ...
 *            }
 *            gAECoreGlobals.currentEventIsAppleEvent = FALSE;
 *            return (status);
 *
 *
 *    pascal OSErr                AEMakeTargetAddress(
 *            AETargetAddressType        aeTargetAddressType,
 *            AEDesc                    *theAddress,
 *            StringPtr                targetName
 *        );
 *
 *        Create a descriptor to send AppleEvents. There are three target types:
 *        kAETargetSelfCurrentProcess    This is the normal call for self-events as
 *                                    would be used by scriptable applications.
 *                                    The AppleEvent manager calls the event
 *                                    handler directly. This is quite efficient.
 *        kAETargetSelfUsingPSN        This send an event to the current application
 *                                    through the event loop. It might be used
 *                                    for debugging.
 *        kAETargetOtherApplication    This calls the AppleEvent browser to select
 *                                    a target application. It would be used by
 *                                    client applications.
 *        On return, targetName may be used for Alerts.
 *
 *    pascal OSErr                AEBrowseForTarget(
 *            ConstStr255Param        dialogPrompt,
 *            ConstStr255Param        listHeader,
 *            PPCFilterUPP            filterProcUPP,
 *            ConstStr255Param        locNBPType,
 *            AEDesc                    *theAddress,
 *            StringPtr                targetName
 *        );
 *
 *        Call the PPCBrowser and create a target descriptor. This is called by
 *        AEMakeTargetAddress(kAETargetOtherApplication, ...).
 *
 *    pascal OSErr                AELocateTarget(
 *            ConstStr255Param        machineName,
 *            const StringPtr            *targetNameVector,
 *            AEDesc                    *theAddress,
 *            StringPtr                actualTargetName
 *        );
 *
 *        Call IPCListPorts to find a named application on a named machine. This
 *        might be used for client-server applications. Only the current zone
 *        is searched. targetNameVector is a vector a possible application strings.
 *
 *
 *        pascal OSErr            AEGotRequiredParams(
 *            const AppleEvent        *theEvent
 *        );
 *
 *        This fails if not all required parameters have been extracted. Call this
 *        after retrieving all required parameters before actually processing the
 *        event. This sets GLOBAL.currentAEStatus to noErr if it succeeds. If
 *        required parameters remain, it returns errAEParamMissed.
 *
 *        pascal Boolean            AEInteractionOK(
 *            AEIdleUPP                aeIdleUPP
 *        );
 *
 *        This should be called before doing any user-interaction, such as alerts
 *        or dialogs. It returns FALSE if interaction is blocked at this time.
 *        The application should provide an idle function UPP. For example,
 *
 *        pascal Boolean
 *        MyAEIdleProc(
 *                const EventRecord        *theEventPtr,
 *                long                    *sleepTime,
 *                RgnHandle                *mouseRgn
 *            )
 *        {
 *                if (theEventPtr->what == kHighLevelEvent)
 *                    return (TRUE);
 *                else {
 *                    *sleepTime = MyProcessThisEvent(theEventPtr);
 *                    return (FALSE);
 *                }
 *        }
 *
 * Access AppleEvent data -- these are needed to process private events.
 * These functions return errAEDescNotFound if the parameter was missing.
 *
 *        OSErr                    AEGetShort(
 *            const AppleEvent        *theEvent,
 *            DescType                parameterKey,
 *            short                    *result;
 *        );
 *        OSErr                    AEGetLong(
 *            const AppleEvent        *theEvent,
 *            DescType                parameterKey,
 *            long                    *result
 *        );
 *        OSErr                    AEGetBoolean(
 *            const AppleEvent        *theEvent,
 *            DescType                parameterKey,
 *            Boolean                    *result
 *        );
 *        OSErr                    AEGetChars(
 *            const AppleEvent        *theEvent,
 *            DescType                parameterKey,
 *            CharsHandle                *result
 *        );
 *        OSErr                    AEGetString(
 *            const AppleEvent        *theEvent,
 *            DescType                parameterKey,
 *            StringPtr                result
 *        );
 *        OSErr                    AEPutShort(
 *            AppleEvent                *theReply,
 *            DescType                parameterKey,
 *            short                    value
 *        );
 *        void                    AEPutLong(
 *            AppleEvent                *theReply,
 *            DescType                parameterKey,
 *            long                    value
 *        );
 *        OSErr                    AEPutBoolean(
 *            AppleEvent                *theReply,
 *            DescType                parameterKey,
 *            Boolean                    value
 *        );
 *        OSErr                    AEPutStringHandle(
 *            AppleEvent                *theReply,
 *            DescType                parameterKey,
 *            const StringHandle        value
 *        );
 *        OSErr                    AEPutCharsHandle(
 *            AppleEvent                *theReply,
 *            DescType                parameterKey,
 *            const CharsHandle        value
 *        );
 *        OSErr                    AEPutString(
 *            AppleEvent                *theReply,
 *            DescType                parameterKey,
 *            constStr255Param        value
 *        );
 */

#ifndef __AppleEventCore__
#define __AppleEventCore__

#include <Types.h>
#include <TextEdit.h>
#include <AppleEvents.h>
#include <Gestalt.h>

/*
 * Define a table used to install event handlers.
 */
typedef struct AEHandlerDefRec {
    AEEventClass            eventClass;
    AEEventID                eventID;
    AEEventHandlerProcPtr    procPtr;
} AEHandlerDefRec, *AEHandlerDefPtr;

/*
 * Define a table used to install coercion handlers - we don't have any.
 */
typedef struct AECoercionDefRec{
    DescType                fromType;
    DescType                toType;
    AECoercePtrProcPtr        procPtr;
} AECoercionDefRec, *AECoercionDefPtr;

/*
 * These are application-provided functions: the application must provide open
 * and quit functions. DoHighLevelEvent will return an error to the AppleEvent
 * Manager if a function is missing, or if the handler returns an error.
 */
typedef pascal OSErr    (*AEOpenAppHandlerFunc)(    /* Open App event handler    */
        long                    refCon                /* Event refCon                */
    );
typedef pascal OSErr    (*AEDocumentHandlerFunc)(    /* Open or Print handler     */
        const FSSpecPtr            fsSpecPtr,
        long                    refCon                /* Event refCon                */
    );
typedef pascal OSErr    (*AEQuitAppHandlerFunc)(    /* Quit App event handler    */
        long                    refCon                /* Event refCon                */
    );
typedef pascal OSErr    (*AEDoScriptHandlerFunc)(    /* 'misc' 'dosc'            */
        Ptr                        scriptPtr,            /* Script text                */
        Size                    scriptPtrLength,    /* Script text length        */
        AppleEvent                *replyEvent,        /* What to tell the caller    */
        long                    refCon                /* refCon from the event    */
    );
typedef pascal void        (*AEUnknownHandlerMsgFunc)(    /* Called on unknown events    */
        ConstStr255Param        messageText
    );
pascal OSErr                InitializeAppleEvents(
        AEOpenAppHandlerFunc    aeOpenAppHandlerFunc,
        AEDocumentHandlerFunc    aeOpenDocHandlerFunc,
        AEDocumentHandlerFunc    aePrintDocHandlerFunc,
        AEQuitAppHandlerFunc    aeQuitAppHandlerFunc,
        AEDoScriptHandlerFunc    aeDoScriptHandlerFunc,
        AEUnknownHandlerMsgFunc    aeUnknownHandlerMsgFunc,
        long                    refCon
    );
pascal OSErr                AEInstallEventHandlers(
        AEHandlerDefPtr            aeHandlerDefPtr,
        long                    refCon
    );
pascal OSErr                AEInstallCoercionHandlers(
        AECoercionDefPtr        aeCoercionDefPtr,
        long                    refCon
    );
pascal OSErr                AEIgnore(
        const AppleEvent        *theEvent,
        AppleEvent                *theReply,
        long                    refCon
    );
pascal Boolean                AEInteractionOK(
        AEIdleUPP                aeIdleUPP
    );
pascal OSErr                AEHandlerSetup(
        const AppleEvent        *theEvent,
        AppleEvent                *theReply,
        long                    refCon
    );
pascal OSErr                AEGotRequiredParams(
        const AppleEvent        *theEvent
    );

typedef enum {
    kAETargetSelfCurrentProcess = 0,
    kAETargetSelfUsingPSN,
    kAETargetOtherApplication
} AETargetAddressType;

pascal OSErr                AEMakeTargetAddress(
        AETargetAddressType        aeTargetAddressType,
        AEDesc                    *theAddress,
        StringPtr                targetName
    );
pascal OSErr                AEBrowseForTarget(
        ConstStr255Param        dialogPrompt,
        ConstStr255Param        listHeader,
        PPCFilterUPP            filterProcUPP,
        ConstStr255Param        locNBPType,
        AEDesc                    *theAddress,
        StringPtr                targetName
    );
pascal OSErr                AELocateTarget(
        ConstStr255Param        machineName,
        const StringPtr            *targetNameVector,
        AEDesc                    *theAddress,
        StringPtr                actualTargetName
    );
pascal OSErr                AEGetShort(
        const AppleEvent        *theEvent,
        DescType                parameterKey,
        short                    *result
    );
pascal OSErr                AEGetLong(
        const AppleEvent        *theEvent,
        DescType                parameterKey,
        long                    *result
    );
pascal OSErr                AEGetBoolean(
        const AppleEvent        *theEvent,
        DescType                parameterKey,
        Boolean                    *result
    );
pascal OSErr                AEGetChars(
        const AppleEvent        *theEvent,
        DescType                parameterKey,
        CharsHandle                *result
    );
pascal OSErr                AEGetString(
        const AppleEvent        *theEvent,
        DescType                parameterKey,
        StringPtr                result
    );
pascal OSErr                AEPutShort(
        AppleEvent                *theReply,
        DescType                parameterKey,
        short                    value
    );
pascal OSErr                AEPutLong(
        AppleEvent                *theReply,
        DescType                parameterKey,
        long                    value
    );
pascal OSErr                AEPutBoolean(
        AppleEvent                *theReply,
        DescType                parameterKey,
        Boolean                    value
    );
pascal OSErr                AEPutStringHandle(
        AppleEvent                *theReply,
        DescType                parameterKey,
        const StringHandle        value
    );
pascal OSErr                AEPutCharsHandle(
        AppleEvent                *theReply,
        DescType                parameterKey,
        const CharsHandle        value
    );
pascal OSErr                AEPutString(
        AppleEvent                *theReply,
        DescType                parameterKey,
        ConstStr255Param        value
    );

/*
 * These globals are defined by the AppleEvent library. They are globalized
 * primarly for debugging convenience. The values in AECoreGlobals are only
 * valid during AppleEvent processing.
 */
typedef struct {
    const AppleEvent        *currentAEEvent;
    AppleEvent                *currentAEReply;
    OSErr                    currentAEStatus;
    DescType                currentAEEventClass;
    DescType                currentAEEventID;
    long                    currentAEIntractionLevel;
    Boolean                    currentEventIsAppleEvent;
    long                    currentAERefCon;
} AECoreGlobals, *AECoreGlobalsPtr;

extern AECoreGlobals        gAECoreGlobals;
extern Boolean                gHasAppleEvents;            /* TRUE if supported    */

#endif /* __AppleEventCore__ */